Skip Headers

Oracle® Label Security Administrator's Guide 10g Release 2 (10.2) Part Number B14267-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 4 Working with Labeled Data

This chapter explains how to

- Use Oracle Label Security features to manage labeled data

- View the value of security attributes for a session

- Change the value of those session attributes

The chapter contains these sections:

- The Policy Label Column and Label Tags

- Presenting the Label

- Filtering Data Using Labels

- Inserting Labeled Data

- Changing Your Session and Row Labels with SA_SESSION

  Note: Many of the examples in this book use the HUMAN_RESOURCES sample policy. Its policy name is HR and its policy label column is HR_LABEL. Unless otherwise noted, the examples assume that the SQL statements are performed on rows within the user's authorization and with full Oracle Label Security policy enforcement in effect.

## 4.1 The Policy Label Column and Label Tags

This section explains how policy label columns in a table or schema are created and filled, using these topics:

- The Policy Label Column

- Label Tags

### 4.1.1 The Policy Label Column

Each policy that is applied to a table creates a column in the database. By default, the data type of the policy label column is NUMBER.

Note: The act of creating a policy does not in itself have any effect on tables or schemas. It only applyies the policy to a table or schema. Refer to these sections: "Creating a Policy with SA_SYSDBA.CREATE_POLICY" Applying a Policy with SA_POLICY_ADMIN.APPLY_TABLE_POLICY Applying a Policy with SA_POLICY_ADMIN.APPLY_SCHEMA_POLICY

Each row's label for that policy is represented by a tag in that column, using the numeric equivalent of the character-string label value. The label tag is automatically generated when the label is created, unless the administrator specifies the tag manually at that time.

The automatic label generation follows the rules established by the administrator while defining the label components, as described in Chapter 2, "Understanding Data Labels and User Labels".

#### 4.1.1.1 Hiding the Policy Label Column

The administrator can decide not to display the column representing a policy by applying the HIDE option to the table. After a policy using HIDE is applied to a table, a user executing a SELECT * or performing a DESCRIBE operation will not see the policy label column. If the policy label column is not hidden, then the label tag is displayed as data type NUMBER. Refer to "The HIDE Policy Column Option".

#### 4.1.1.2 Example 1: Numeric Column Data Type (NUMBER)

    SQL> describe emp;
     Name                                      Null?    Type
     ----------------------------------------- -------- --------
     EMPNO                                     NOT NULL NUMBER(4)
     ENAME                                              CHAR(10)
     JOB                                                CHAR(9)
     MGR                                                NUMBER(4)
     SAL                                                NUMBER(7,2)
     DEPTNO                                    NOT NULL NUMBER(2)
     HR_LABEL                                           NUMBER(10)

#### 4.1.1.3 Example 2: Numeric Column Data Type with Hidden Column

Notice that in this example, the HR_LABEL column is not displayed.

    SQL> describe emp;
     Name                                      Null?    Type
     ----------------------------------------- -------- --------
     EMPNO                                     NOT NULL NUMBER(4)
     ENAME                                              CHAR(10)
     JOB                                                CHAR(9)
     MGR                                                NUMBER(4)
     SAL                                                NUMBER(7,2)
     DEPTNO                                    NOT NULL NUMBER(2)

### 4.1.2 Label Tags

As noted in Chapter 2, "Understanding Data Labels and User Labels", the administrator first defines a set of label components to be used in a policy. When creating labels, the administrator specifies the set of valid combinations of components that can make up a label, that is, a level optionally combined with one or more groups or compartments. Each such valid label within a policy is uniquely identified by an associated numeric tag assigned by the administrator or generated automatically upon its first use. Manual definition has the advantage of allowing the administrator to control the ordering of label values when they are sorted or logically compared.

However, label tags must be unique across all policies in the database. When you use multiple policies in a database, you cannot use the same numeric label tag in different policies. Remember that each label tag uniquely identifies one label, and that numeric tag is what is stored in the data rows, not the label's character-string representation.

This section contains these topics:

- Manually Defining Label Tags to Order Labels

- Manually Defining Label Tags to Manipulate Data

- Automatically Generated Label Tags

#### 4.1.2.1 Manually Defining Label Tags to Order Labels

By manually defining label tags, the administrator can implement a data manipulation strategy that permits labels to be meaningfully sorted and compared. To do this, the administrator predefines all of the labels to be associated with protected data, and assigns to each label a meaningful label tag value. Manually assigned label tags can have up to eight digits. The value of a label tag must be greater than zero.

It may be advantageous to implement a strategy in which label tag values are related to the numeric values of label components. In this way, you can use the tags to group data rows in a meaningful way. This approach, however, is not mandatory. It is good practice to set tags for labels of higher sensitivity to a higher numeric value than tags for labels of lower sensitivity.

Table 4-1 illustrates a set of label tags that have been assigned by an administrator. Notice that, in this example, the administrator has based the label tag value on the numeric form of the levels, compartments, and rows that were discussed in Chapter 2, "Understanding Data Labels and User Labels".

Table 4-1 Administratively Defined Label Tags (Example)

Label Tag | Label String
--- | ---
10000 | P
20000 | C
21000 | C:FNCL
21100 | C:FNCL,OP
30000 | S
31110 | S:OP:WR
40000 | HS
42000 | HS:OP

In this example, labels with a level of PUBLIC begin with "1", labels with a level of CONFIDENTIAL begin with "2", labels with a level of SENSITIVE begin with "3", and labels with a level of HIGHLY_SENSITIVE begin with "4".

Labels with the FINANCIAL compartment then come in the 1000 range, labels with the compartment OP are in the 1100 range, and so on. The tens place is used to indicate the group WR, for example.

Another strategy might be completely based on groups, where the tags might be 3110, 3120, 3130, and so on.

Note, however, that label tags identify the whole label, independent of the numeric values assigned for the individual label components. The label tag is used as a whole integer, not as a set of individually evaluated numbers.

#### 4.1.2.2 Manually Defining Label Tags to Manipulate Data

An administratively defined label tag can serve as a convenient way to reference a complete label string (that is, a particular combination of label components). As illustrated in Table 4-1, for example, the tag "31110" could stand for the complete label string "S:OP:WR".

Label tags can be used as a convenient way to partition data. For example, all data with labels in the range 1000 - 1999 could be placed in tablespace A, all data with labels in the range 2000 - 2999 could be placed in tablespace B, and so on.

This simplified notation also comes in handy when there is a finite number of labels and you need to perform various operations upon them. Consider a situation in which one company hosts a human resources system for many other companies. Assume that all users from Company Y have the label "C:ALPHA:CY", for which the tag "210" has been set. To determine the total number of application users from Company Y, the host administrator can enter:

    SELECT * FROM tab1
      WHERE hr_label = 210;

#### 4.1.2.3 Automatically Generated Label Tags

Dynamically generated label tags, illustrated in Table 4-2, have 10 digits, with no relationship to numbers assigned to any label component. There is no way to group the data by label.

Table 4-2 Generated Label Tags (Example)

Label Tag | Label String
--- | ---
100000020 | P
100000052 | C
100000503 | C:FNCL
100000132 | C:FNCL,OP
100000003 | S
100000780 | S:OP:WR
100000035 | HS
100000036 | HS:OP

See Also: "Creating a Valid Data Label with SA_LABEL_ADMIN.CREATE_LABEL" "Planning a Label Tag Strategy to Enhance Performance"

## 4.2 Assigning Labels to Data Rows

For rows that are being inserted, refer to Inserting Labeled Data.

For existing data rows, labels can be assigned by a labeling function that you create. In such a function, you specify the exact table and row conditions defining what label to insert. The function can be named in the call to apply a policy to a table or schema, or in an update by the administrator.

See Also: "Using a Labeling Function" Applying a Policy with SA_POLICY_ADMIN.APPLY_TABLE_POLICY. "Applying a Policy with SA_POLICY_ADMIN.APPLY_SCHEMA_POLICY"

## 4.3 Presenting the Label

When you retrieve labels, you do not automatically obtain the character string value. By default, the label tag value is returned. Two label manipulation functions enable you to convert the label tag value to and from its character string representation:

- Converting a Character String to a Label Tag, with CHAR_TO_LABEL

- Converting a Label Tag to a Character String, with LABEL_TO_CHAR

### 4.3.1 Converting a Character String to a Label Tag, with CHAR_TO_LABEL

Use the CHAR_TO_LABEL function to convert a character string to a label tag. This function returns the label tag for the specified character string.

Syntax:

    FUNCTION CHAR_TO_LABEL (
         policy_name     IN VARCHAR2,
         label_string    IN VARCHAR2)
    RETURN NUMBER;

Example:

    INSERT INTO emp (empno,hr_label)
    VALUES (999, CHAR_TO_LABEL('HR','S:A,B:G5');

Here, `HR` is the label policy name, `S` is a sensitivity level, `A,B` compartments, and `G5` a group.

### 4.3.2 Converting a Label Tag to a Character String, with LABEL_TO_CHAR

When you query a table or view, you automatically retrieve all of the rows in the table or view that satisfy the qualifications of the query and are dominated by your label. If the policy label column is not hidden, then the label tag value for each row is displayed. You must use the LABEL_TO_CHAR function to display the character string value of each label.

Note that all conversions must be explicit. There is no automatic casting to and from tag and character string representations.

Syntax:

    FUNCTION LABEL_TO_CHAR (
         label                 IN NUMBER)
    RETURN VARCHAR2;

#### 4.3.2.1 LABEL_TO_CHAR Examples

The examples that follow illustrate the use of LABEL_TO_CHAR.

##### 4.3.2.1.1 Example 1:

To retrieve the label of a row from a table or view, specify the policy label column in the SELECT statement as follows:

    SELECT label_to_char (hr_label) AS label, ename FROM tab1;
      WHERE ename = 'RWRIGHT';

This statement returns the following:

    LABEL          ENAME
    ------------   ----------
    S:A,B:G1       RWRIGHT

##### 4.3.2.1.2 Example 2:

You can also specify the policy label column in the WHERE clause of a SELECT statement. The following statement displays all rows that have the policy label `S:A,B:G1`

    SELECT label_to_char (hr_label) AS label,ename FROM emp
      WHERE hr_label = char_to_label ('HR', 'S:A,B:G1');

This statement returns the following:

    LABEL           ENAME
    -------------   ---------
    S:A,B:G1        RWRIGHT
    S:A,B:G1        ESTANTON

Alternatively, you could use a more flexible statement to look up data that contains the string "S:A,B:G1" anywhere in the text of the HR_LABEL column:

    SELECT label_to_char (hr_label) AS label,ename FROM emp
      WHERE label_to_char (hr_label) like '%S:A,B:G1%';

If you do not use the LABEL_TO_CHAR function, then you will see the label tag.

##### 4.3.2.1.3 Example 3:

The following example is with the numeric column data type (NUMBER) and dynamically generated label tags, but without using the LABEL_TO_CHAR function. If you do not use the LABEL_TO_CHAR function, then you will see the label tag.

    SQL> select empno, hr_label from emp
         where ename='RWRIGHT';

    EMPNO      HR_LABEL
    ---------- ----------
    7839       1000000562

#### 4.3.2.2 Retrieving All Columns from a Table When the Policy Label Column Is Hidden

If the policy label column is hidden, then it is not automatically returned when you select all columns from a table using the SELECT * command. You must explicitly specify that you want to retrieve the label. For example, to retrieve all columns from the DEPT table (including the policy label column in its character representation), enter the following:

    SQL> column label format a10
    SQL> select label_to_char (hr_label) as label, dept.*
      2  from dept;

Running these SQL statements returns the following data:

Table 4-3 Data Returned from Sample SQL Statements re Hidden Column

LABEL | DEPTNO | DNAME | LOC
--- | --- | --- | ---
L1 | 10 | ACCOUNTING | NEW YORK
L1 | 20 | RESEARCH | DALLAS
L1 | 30 | SALES | CHICAGO
L1 | 40 | OPERATIONS | BOSTON

By contrast, if you do not explicitly specify the HR_LABEL column, the label is not displayed at all. Note that while the policy column name is on a policy basis, the HIDE option is on a table-by-table basis.

See Also: "The HIDE Policy Column Option"

## 4.4 Filtering Data Using Labels

During the processing of SQL statements, Oracle Label Security makes calls to the security policies defined in the database by the create and apply procedures discussed in Chapter 6, "Creating an Oracle Label Security Policy" and Chapter 9, "Applying Policies to Tables and Schemas". For SELECT statements, the policy filters the data rows that the user is authorized to see. For INSERT, UPDATE, and DELETE statements, Oracle Label Security permits or denies the requested operation, based on the user's authorizations.

This section contains these topics:

- Using Numeric Label Tags in WHERE Clauses

- Ordering Labeled Data Rows

- Ordering by Character Representation of Label

- Determining Upper and Lower Bounds of Labels

- Merging Labels with the MERGE_LABEL Function

  See Also: "Partitioning Data Based on Numeric Label Tags"

### 4.4.1 Using Numeric Label Tags in WHERE Clauses

This section describes techniques of using numeric label tags in WHERE clauses of SELECT statements.

When using labels in the NUMBER format, the administrator can set up labels so that a list of their label tags distinguishes the different levels. Comparisons of these numeric label tags can be used for ORDER BY processing, and with the logical operators.

For example, if the administrator has assigned all UNCLASSIFIED labels to the 1000 range, all SENSITIVE labels to the 2000 range, and all HIGHLY_SENSITIVE labels to the 3000 range, then you can list all SENSITIVE records by entering:

    SELECT * FROM emp
    WHERE hr_label BETWEEN 2000 AND 2999;

To list all SENSITIVE and UNCLASSIFIED records, you can enter:

    SELECT * FROM emp
    WHERE hr_label <3000;

To list all HIGHLY_SENSITIVE records, you can enter:

    SELECT * FROM emp
    WHERE hr_label=3000;

Note: Remember that such queries have meaning only if the administrator has applied a numeric ordering strategy to the label tags that he or she originally assigned to the labels. In this way, the administrator can provide for convenient dissemination of data. If, however, the label tag values are generated automatically, then there is no intrinsic relationship between the value of the tag and the order of the labels.

Alternatively, you can use dominance relationships to set up an ordering strategy.

See Also: "Using Dominance Functions"

### 4.4.2 Ordering Labeled Data Rows

You can perform an ORDER BY referencing the policy label column to order rows by the numeric label tag value that the administrator has set. For example:

    SELECT * from emp
    ORDER BY hr_label;

Notice that no functions were necessary in this statement. The statement made use of label tags set up by the administrator.

Note: Again, such queries have meaning only if the administrator has applied a numeric ordering strategy to the label tags originally assigned to the labels.

### 4.4.3 Ordering by Character Representation of Label

Using the LABEL_TO_CHAR function, you can order data rows by the character representation of the label. For example, the following statement returns all rows sorted by the text order of the label:

    SELECT * FROM emp
    ORDER BY label_to_char (hr_label);

### 4.4.4 Determining Upper and Lower Bounds of Labels

This section describes the Oracle Label Security functions that determine the least upper bound or the greatest lower bound of two or more labels. Two single-row functions operate on each row returned by a query. They return one result for each row.

- Finding Least Upper Bound with LEAST_UBOUND

- Finding Greatest Lower Bound with GREATEST_LBOUND

  Note: In all functions that take multiple labels, the labels must all belong to the same policy.

#### 4.4.4.1 Finding Least Upper Bound with LEAST_UBOUND

The LEAST_UBOUND (LUBD) function returns a character string label that is the least upper bound of label1 and label2: that is, the one label that dominates both. The least upper bound is the highest level, the union of the compartments in the labels, and the union of the groups in the labels. For example, the least upper bound of HIGHLY_SENSITIVE:ALPHA and SENSITIVE:BETA is HIGHLY_SENSITIVE:ALPHA,BETA.

Syntax:

    FUNCTION LEAST_UBOUND (
         label1                    IN NUMBER,
         label2                    IN NUMBER)
    RETURN VARCHAR2;

The LEAST_UBOUND function is useful when joining rows with different labels, because it provides a high water mark label for joined rows.

The following query compares each employee's label with the label of his or her department, and returns the higher label, whether it be in the EMP table or the DEPT table.

    SELECT ename,dept.deptno,
      LEAST_UBOUND(emp.hr_label,dept.hr_label) as label
      FROM emp, dept
      WHERE emp.deptno=dept.deptno;

This query returns the following data:

Table 4-4 Data Returned from Sample SQL Statements re Least_UBound

ENAME | DEPTNO | LABEL
--- | --- | ---
KING | 10 | L3:M:D10
BLAKE | 30 | L3:M:D30
CLARK | 10 | L3:M:D10
JONES | 20 | L3:M:D20
MARTIN | 30 | L2:E:D30

#### 4.4.4.2 Finding Greatest Lower Bound with GREATEST_LBOUND

The GREATEST_LBOUND (GLBD) function can be used to determine the lowest label of the data that can be involved in an operation, given two different labels. It returns a character string label that is the greatest lower bound of label1 and label2. The greatest lower bound is the lowest level, the intersection of the compartments in the labels and the groups in the labels. For example, the greatest lower bound of HIGHLY_SENSITIVE:ALPHA and SENSITIVE is SENSITIVE.

Syntax:

    FUNCTION GREATEST_LBOUND (
         label1                  IN NUMBER,
         label2                  IN NUMBER)
    RETURN VARCHAR2;

### 4.4.5 Merging Labels with the MERGE_LABEL Function

The MERGE_LABEL function is a utility for merging two labels together. It accepts the character string form of two labels and the three-character specification of a merge format. Its syntax is as follows:

Syntax:

    FUNCTION merge_label (label1 IN number,
                          label2 IN number,
                          merge_format IN VARCHAR2)
    RETURN number;

The valid merge format is specified with a three-character string:

<highest level or lowest level><union or intersection of compartments><union or intersection of groups>

- The first character indicates whether to merge using the highest level or the lowest level of the two labels.

- The second character indicates whether to merge using the union or the intersection of the compartments in the two labels.

- The third character indicates whether to merge using the union or the intersection of the groups in the two labels.

The following table defines the MERGE_LABEL format constants.

Table 4-5 MERGE_LABEL Format Constants

Format Specification | Data Type | Constant | Meaning | Positions in Which Format Is Used
--- | --- | --- | --- | ---
max_lvl_fmt | CONSTANT varchar2(1) | H | Maximum level | First (level)
min_lvl_fmt | CONSTANT varchar2(1) | L | Minimum level | First (Level)
union_fmt | CONSTANT varchar2(1) | U | Union of the two labels | Second (compartments) and Third (groups)
inter_fmt | CONSTANT varchar2(1) | I | Intersection of the two labels | Second (compartments) and Third (groups)
minus_fmt | CONSTANT varchar2(1) | M | Remove second label from first label | Second (compartments) and Third (groups)
null_fmt | CONSTANT varchar2(1) | N | If specified in compartments column, returns no compartments. If specified in groups column, returns no groups. | Second (compartments) and Third (groups)

For example, HUI specifies the highest level of the two labels, union of the compartments, intersection of the groups.

The MERGE_LABEL function is particularly useful to developers if the LEAST_UBOUND function does not provide the intended result. The LEAST_UBOUND function, when used with two labels containing groups, may result in a less sensitive data label than expected. The MERGE_LABEL function enables you to compute an intersection on the groups, instead of the union of groups that is provided by the LEAST_UBOUND function.

For example, if the label of one data record contains the group UNITED_STATES, and the label of another data record contains the group UNITED_KINGDOM, and the LEAST_UBOUND function is used to compute the least upper bound of these two labels, then the resulting label would be accessible to users authorized for either the UNITED_STATES or the UNITED_KINGDOM.

If, by contrast, the MERGE_LABEL function is used with a format clause of HUI, then the resulting label would contain the highest level, the union of the compartments, and no groups. This is because UNITED_STATES and UNITED_KINGDOM do not intersect.

## 4.5 Inserting Labeled Data

When you insert data into a table protected by a policy under Oracle Label Security, a numeric label value tag must be supplied, usually in the INSERT statement itself.

To do this, you must explicitly specify the tag for the desired label or explicitly convert the character string representation of the label into the correct tag. Note that this does not mean generating new label tags, but referencing the correct tag. When Oracle Label Security is using Oracle Internet Directory, the only permissible labels (and corresponding tags) are those pre-defined by the administrator and already in Oracle Internet Directory.

The only times an INSERT statement may omit a label value are:

1. if the LABEL_DEFAULT enforcement option was specified when the policy was applied, or

2. if no enforcement options were specified when the policy was applied and LABEL_DEFAULT was specified when the policy was created, or

3. if the statement applying the policy named a labeling function.

In cases 1 and 2, the user's session default row label is used as the inserted row's label. In case 3, the inserted row's label is created by that labeling function.

See Also: "Applying a Policy with SA_POLICY_ADMIN.APPLY_TABLE_POLICY", or to schemas "Creating a Policy with SA_SYSDBA.CREATE_POLICY" "Using a Labeling Function" All of Chapter 8, "Implementing Policy Enforcement Options and Labeling Functions" regarding reading and writing labeled data (and labels) and according to policy enforcement options

This section explains the different ways to specify a label in an INSERT statement:

- Inserting Labels Using CHAR_TO_LABEL

- Inserting Labels Using Numeric Label Tag Values

- Inserting Data Without Specifying a Label

- Inserting Data When the Policy Label Column Is Hidden

- Inserting Labels Using TO_DATA_LABEL

### 4.5.1 Inserting Labels Using CHAR_TO_LABEL

To insert a row label, you can specify the label character string and then transform it into a label using the CHAR_TO_LABEL function. Using the definition for table emp, the following example shows how to insert data with explicit labels:

    INSERT INTO emp (ename,empno,hr_label)
    VALUES ('ESTANTON',10,char_to_label ('HR', 'SENSITIVE'));

### 4.5.2 Inserting Labels Using Numeric Label Tag Values

You can insert data using the numeric label tag value of a label, rather than using the CHAR_TO_LABEL function. For example, if the numeric label tag for SENSITIVE is 3000, it would look like this:

    INSERT INTO emp (ename, empno, hr_label)
    VALUES ('ESTANTON', 10, 3000);

### 4.5.3 Inserting Data Without Specifying a Label

If LABEL_DEFAULT is set, or if there is a labeling function applied to the table, then you do not need to specify a label in your INSERT statements. The label will be provided automatically. You can enter the following command:

    INSERT INTO emp (ename, empno)
    VALUES ('ESTANTON', 10);

The resulting row label is set according to the default value (or by a labeling function).

See Also: "Overview of Policy Enforcement Options" "The Label Management Enforcement Options" "Using a Labeling Function" "Applying a Policy with SA_POLICY_ADMIN.APPLY_TABLE_POLICY" "Creating a Policy with SA_SYSDBA.CREATE_POLICY"

### 4.5.4 Inserting Data When the Policy Label Column Is Hidden

If the label column is hidden, then the existence of the column is transparent to the insertion of data. INSERT statements can be written that do not explicitly list the table columns and do not include a value for the label column. The session's row label is used to label the data, or a labeling function is used if one was specified when the policy was applied to the table or schema.

You can insert into a table without explicitly naming the columns, as long as you specify a value for each non-hidden column in the table. The following example shows how to insert a row into the table described in "Example 2: Numeric Column Data Type with Hidden Column":

    INSERT INTO emp
    VALUES ('196','ESTANTON',Technician,RSTOUT,50000,10);

Its label will be one of the following three possibilities:

- The label you specify

- The label established by the LABEL_DEFAULT option of the policy being applied

- The label created by a labeling function named by the policy being applied

  Note: If the policy label column is not hidden, then you must explicitly include a label value (possibly null, indicated by a comma) in the INSERT statement.

### 4.5.5 Inserting Labels Using TO_DATA_LABEL

Note: When Oracle Label Security is installed to work with Oracle Internet Directory, dynamic label generation is not allowed, because labels are managed centrally in Oracle Internet Directory, using `olsadmintool` commands. Refer to Appendix B, "Command-line Tools for Label Security Using Oracle Internet Directory" So, when Oracle Label Security is directory-enabled, this function, TO_DATA_LABEL, is not available and will generate an error message if used.

If you are generating new labels dynamically as you insert data, then you can use the TO_DATA_LABEL function to guarantee that this produces valid data labels. To do this, you must the have EXECUTE authority on the TO_DATA_LABEL function.

Whereas the CHAR_TO_LABEL function requires that the label already be an existing data label for the transaction to succeed, the TO_DATA_LABEL does not have this requirement. It will automatically create a valid data label.

For example:

    INSERT INTO emp (ename, empno, hr_label)
    VALUES ('ESTANTON', 10, to_data_label ('HR', 'SENSITIVE'));

Note: The TO_DATA_LABEL function must be explicitly granted to individuals, in order to be used. Its usage should be tightly controlled.

See Also: Chapter 9, "Applying Policies to Tables and Schemas" for more information about inserting, updating, and deleting labeled data

## 4.6 Changing Your Session and Row Labels with SA_SESSION

During a given session, a user can change his or her labels, within the authorizations set by the administrator.

This section contains these topics:

- SA_SESSION Functions to Change Session and Row Labels

- Changing the Session Label with SA_SESSION.SET_LABEL

- Changing the Row Label with SA_SESSION.SET_ROW_LABEL

- Restoring Label Defaults with SA_SESSION.RESTORE_DEFAULT_LABELS

- Saving Label Defaults with SA_SESSION.SAVE_DEFAULT_LABELS

- Viewing Session Attributes with SA_SESSION Functions

### 4.6.1 SA_SESSION Functions to Change Session and Row Labels

The following functions enable the user to change the session and row labels:

Table 4-6 Functions to Change Session Labels

Function | Purpose
--- | ---
SA_SESSION.SET_LABEL | Lets the user set a new level and new compartments and groups to which he or she has read access
SA_SESSION.SET_ROW_LABEL | Lets the user set the default row label that will be applied to new rows
SA_SESSION.RESTORE_DEFAULT_LABELS | Lets the user reset the current session label and row label to the stored default settings
SA_SESSION.SAVE_DEFAULT_LABELS | Lets the user store the current session label and row label as the default for future sessions

### 4.6.2 Changing the Session Label with SA_SESSION.SET_LABEL

Use the SET_LABEL procedure to set the label of the current database session.

Syntax:

    PROCEDURE SET_LABEL (policy_name IN VARCHAR2,
                         label IN VARCHAR2);

Parameter | Specifies
--- | ---
policy_name | The name of an existing policy.
label | The value to set as the label

A user can set the session label to:

- Any level equal to or less than the maximum, and equal to or greater than the minimum level

- Include any compartments in the authorized compartment list

- Include any groups in the authorized group list. (Subgroups of authorized groups are implicitly included in the authorized list.)

Note that if you change the session label, this change may affect the value of the session's row label. The session's row label contains the subset of compartments and groups for which the user has write access. This may or may not be equivalent to the session label. For example, if you use the SA_SESSION.SET_LABEL command to set your current session label to C:A,B:US and you have write access only on the A compartment, then your row label would be set to C:A.

See Also: "SA_USER_ADMIN.SET_DEFAULT_LABEL"

### 4.6.3 Changing the Row Label with SA_SESSION.SET_ROW_LABEL

Use the SET_ROW_LABEL procedure to set the default row label value for the current database session. The compartments and groups in the label must be a subset of the compartments and groups in the session label to which the user has write access. When the LABEL_DEFAULT option is set, this row label value is used on insert if the user does not explicitly specify the label.

Syntax:

    PROCEDURE SET_ROW_LABEL (policy_name IN VARCHAR2,
                             row_label IN VARCHAR2);

Parameter | Specifies
--- | ---
policy_name | The name of an existing policy
label | The value to set as the default row label

If the SA_SESSION.SET_ROW_LABEL procedure is not used to set the default row label value, then this value is automatically derived from the session label. It contains the level of the session label and the subset of the compartments and groups in the session label for which the user has write authorization.

The row label is automatically reset if the session label changes. For example, if you change your session level from HIGHLY_SENSITIVE to SENSITIVE, then the level component of the row label automatically changes to SENSITIVE.

The user can set the row label independently, but only to include:

- A level that is less than or equal to the level of the session label, and greater than or equal to the user's minimum level

- A subset of the compartments and groups from the session label, for which the user is authorized to have write access

If the user tries to set the row label to an invalid value, then the operation is not permitted and the row label value is unchanged.

See Also: "SA_USER_ADMIN.SET_ROW_LABEL"

### 4.6.4 Restoring Label Defaults with SA_SESSION.RESTORE_DEFAULT_LABELS

The RESTORE_DEFAULT_LABELS procedure restores the session label and row label to those stored in the data dictionary. This command is useful to reset values after a SA_SESSION.SET_LABEL command has been processed.

Syntax:

    PROCEDURE RESTORE_DEFAULT_LABELS (policy_name in VARCHAR2);

where policy_name provides the name of an existing policy.

### 4.6.5 Saving Label Defaults with SA_SESSION.SAVE_DEFAULT_LABELS

The SAVE_DEFAULT_LABELS procedure stores the current session label and row label as your initial session label and default row label. It permits you to change your defaults to reflect your current session label and row label. The saved labels will be used as the initial default settings for future sessions.

Syntax:

    PROCEDURE SAVE_DEFAULT_LABELS (policy_name in VARCHAR2);

where policy_name provides the name of an existing policy.

When you log in to a database, your default session label and row label are used to initialize the session label and row label. When the administrator originally authorized your Oracle Label Security labels, he or she also defined your default level, default compartments, and default groups. If you change your session label and row label, and want to save these values as the default labels, you can use the SA_SESSION.SAVE_DEFAULT_LABELS procedure.

This procedure is useful if you have multiple sessions and want to be sure that all additional sessions have the same labels. You can save the current labels as the default, and all future sessions will have these as the initial labels.

Consider a situation in which you connect to the database through Oracle Forms and want to run a report. By saving the current session labels as the default before you call Oracle Reports, you ensure that Oracle Reports will initialize at the same labels as are being used by Oracle Forms.

Note: The SA_SESSION.SAVE_DEFAULT_LABELS procedure overrides the settings established by the administrator.

### 4.6.6 Viewing Session Attributes with SA_SESSION Functions

You can use SA_SESSION functions to view the policy attributes for a session.

- USER_SA_SESSION View to Return All Security Attributes

- Functions to Return Individual Security Attributes

#### 4.6.6.1 USER_SA_SESSION View to Return All Security Attributes

You can display security attribute values by using the USER_SA_SESSION view. Access to this view is PUBLIC. It lets you see the security attributes for your current session. For example:

Table 4-7 Security Attribute Names and Types

Name | Null? | Type
--- | --- | ---
POLICY_NAME | NOT NULL | VARCHAR2(30)
SA_USER_NAME |  | VARCHAR2(4000)
PRIVS |  | VARCHAR2(4000)
MAX_READ_LABEL |  | VARCHAR2(4000)
MAX_WRITE_LABEL |  | VARCHAR2(4000)
MIN_LEVEL |  | VARCHAR2(4000)
LABEL |  | VARCHAR2(4000)
COMP_WRITE |  | VARCHAR2(4000)
GROUP_WRITE |  | VARCHAR2(4000)
ROW_LABEL |  | VARCHAR2(4000)

#### 4.6.6.2 Functions to Return Individual Security Attributes

The SA_SESSION functions take a policy_name as the only input parameter. They return VARCHAR2 character string values for use in SQL statements.

Table 4-8 SA_SESSION Functions to View Security Attributes

Function | Purpose
--- | ---
SA_SESSION.PRIVS | Returns the set of current session privileges, in a comma-delimited list
SA_SESSION.MIN_LEVEL | Returns the minimum level authorized for the session
SA_SESSION.MAX_LEVEL | Returns the maximum level authorized for the session
SA_SESSION.COMP_READ | Returns a comma-delimited list of compartments that the user is authorized to read
SA_SESSION.COMP_WRITE | Returns a comma-delimited list of compartments that the user is authorized to write. This is a subset of SA_SESSION.COMP_READ.
SA_SESSION.GROUP_READ | Returns a comma-delimited list of groups that the user is authorized to read
SA_SESSION.GROUP_WRITE | Returns a comma-delimited list of groups that the user is authorized to write. This is a subset of SA_SESSION.GROUP_READ.
SA_SESSION.LABEL | Returns the session label (the level, compartments, and groups) with which the user is currently working. The user can change this value with SA_SESSION.SET_LABEL. Refer to Changing the Session Label with SA_SESSION.SET_LABEL.
SA_SESSION.ROW_LABEL | Returns the session's default row label value. The user can change this value with SA_SESSION.SET_ROW_LABEL. Refer to Changing the Row Label with SA_SESSION.SET_ROW_LABEL.
SA_SESSION.SA_USER_NAME | Returns the username associated with the current Oracle Label Security session

For example, the following statement shows the current session label for the Human Resources policy:

    SQL> select sa_session.label ('human_resources')
      2  from dual;

    SA_SESSION.LABEL('HUMAN_RESOURCES')
    ---------------------------------------------
    L3:M,E

See Also: "Using SA_UTL Functions to Set and Return Label Information" for additional functions that return numeric label tags and BOOLEAN values